\chapter{Edycja dokumentów w~systemie \LaTeX}

\section{Krótka nota o~systemie \LaTeX}
\TeX jest systemem składu komputerowego stworzonym przez Donalda E. Knutha. \LaTeX nie jest samodzielnym środowiskiem programistycznym. 
Jest to jedynie zestaw instrukcji (poleceń, makrodefinicji, makr) stanowiących nadbudowę dla systemu składu \TeX.
Tworzenie tekstu w~LaTeX-u opiera się na zasadzie WYSIWYM (What You See Is What You Mean - To co widzisz jest tym, o~czym myślisz). 
Od zasady WYSIWYG odróżnia go to, że autor tekstu określa jedynie logiczną strukturę dokumentu natomiast samym graficznym "ułożeniem" tekstu na stronie zajmuje się \TeX


\section{Przegląd programów do tworzenia dokumentów \LaTeX}
Dokumenty \LaTeX{} mogą być tworzone w~dowolnym programie do edycji plików tekstowych. Ze wzg. jednak na ergonomię pracy należy wybrać wspierający skład dokumentu \LaTeX. W~środowisku Linux mamy dostępne np.:
\begin{itemize}
\item texmaker - darmowy, nowoczesny, wieloplatformowy edytor dokumentów \LaTeX{} dla systemów linux, macosx i~windows, który łączy wiele narzędzi potrzebnych do tworzenia dokumentów \LaTeX{} w~jednej aplikacji. Texmaker wspiera sprawdzanie pisowni, autouzupełnianie, zawijanie kodu, zawiera wbudowaną przeglądarkę dokumentów PDF z~wsparciem dla synctex (powiązanie miejsce w~kodzie - miejsce w~PDF). Łatwy w~konfiguracji i~użyciu. Licencja: GPL.
\item TeXstudio - projekt typu open-source, zintegrowane środowisko do tworzenia dokumentów \LaTeX. Edytor kodu dysponuje mechanizmem kolorowania składni, autouzupełniania, generowania (kompilacji) wyjściowego dokumentu, a~także wielu dostępnych w~menu predefiniowanych oznaczeń matematycznych, liter czy znaków oraz udogodnienia w~stylu metody "przeciągnij i~upuść" dla plików graficznych.
\item Lyx - edytor dokumentów oparty na licencji GPL. Sam program bazuje na LaTeXu, jednak wprowadzana treść jest już widoczna jako sformatowana - "pogrubiony tekst to faktycznie pogrubiony tekst, akapit jest akapitem, a~rozdział rozdziałem" (http://www.dobreprogramy.pl/Druedain)
LyX zapisuje dokumenty w~formacie tekstowym wzorowanym na XML-u. Na czas kompilacji dokumentu LyX konwertuje dokument ze swojego formatu do formatu LaTeX-a.
\item Vim - wysoce konfigurowalny edytor tekstu, którego zadaniem jest ukazanie dużych możliwości edytora 'Vi' - domyślnej aplikacji do edycji tekstu w~większości systemach operacyjnych z~rodziny Unix. Jest to program mały, zgrabny, użyteczny, szybki, konfiguracyjny.
\end{itemize}

Będziemy pracować w~\textbf{texstudio} ponieważ to zintegrowane środowisko zawiera wszystkie elementy, których potrzebujemy, by praca była zarówno możliwa, jak również wygodna:
umożliwia kompilację (również z~dowolnego pliku w~projekcie, jeśil wskażemy plik główny) podgląd wynikowego dokumentu, wspiera sprawdzanie pisowni - również w~języku polskim, koloruje składnię, 
umożliwia zapisanie sesji i~automatycze jej przywracanie po ponownym uruchomieniu programu


\section{Podstawowa struktura dokumentu - głównego pliku}
\label{sec:PodstawowaStrukturaGlownegoDokumentu}
W \LaTeX{} plik źródłowy posiada określoną strukturę - każdy plik źródłowy składa się z~dwóch części: preambuły oraz części
głównej. Preambuła powinna się rozpoczynać od instrukcji:
\begin{verbatim}
\documentclass{...}
np. \documentclass[12pt]{book} 
\end{verbatim}
w którym określamy klasę dokumentu. Jako parametry można podawać m. in.
\begin{itemize}
\item stopień pisma zasadniczego
\item wymiar papieru
\item opcje dotyczące wzorów matematycznych, ustalenia składu dwukolumnowego
\end{itemize}

Następnie poleceniami 
\begin{verbatim}
\usepackage{...}
\end{verbatim}
dołącza się potrzebne pakiety

a właściwą treść dokumentu pomiędzy
\begin{verbatim}
\begin{document}
\ldots
\end{document}
\end{verbatim}

Powyższą strukturę wprowadzono w~środowisku \verb|%verbatim|, nieinterpretowanym przez \TeX.


\subsection{Użyteczne pakiety}
Pakiety rozszerzają możliwości \LaTeX-a o~opcje takie jak dołączanie grafiki, kolorowanie tekstu, automatycznego łamania dużych tabel itp.

Dla dokumentów w~języku polskim należy zadbać o~ustawienie strony kodowej pozwalającej na wprowadzanie polskich znaków oraz słownik łamania wyrazów języka polskiego:
\begin{verbatim}
\usepackage[utf8]{inputenc}
\usepackage{polski}
\end{verbatim}

Pakiet geometry, w~którym określamy m.in. wymiary kartki i~marginesów
\begin{verbatim}
\usepackage[a4paper, left=2.5cm, right=2.5cm, top=3.5cm, 
	bottom=3.5cm, headsep=1.2cm]{geometry}
\end{verbatim}


Pakiet stowarzyszenia American Mathematical Society do wprowadzania wzorów matematycznych, ułatwia pisanie formuł i~ulepsza sposób ich prezentacji
\begin{verbatim}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\end{verbatim}
Podstawowy pakiet służący włączaniu grafiki do dokumentów LaTeX'owych
\begin{verbatim}
\usepackage{graphicx}
Dostępne opcje:
- scale - skala rysunku 
- width - szerokość 
- height - wysokość
- angle - kąt obrotu
- totalheight - istotne przy dokonywaniu obrotów)
- keepaspectratio - obiekt nie przekroczy podanych wymiarów
- viewport - wybranie tylko fragmentu, wymiar jako cztery liczby
\end{verbatim}
\section{Podział dużego dokumentu na wiele plików}
\LaTeX{} zwraca dużą uwagę na strukturę dokumentu. Warto zadbać też o~przemyślaną strukturę katalogową, również dla wygody użytkowania - umieszczenie wszystkich treści w~jednym pliku utrudniałoby edycję i~zmniejszało przejrzystość projektu.
\begin{itemize}
\item Nazwa katalogu głównego musi opisać rodzaj dokumentu np. pracaInzynierskaJanNowak, dokumentacjaUMPandroid, narzedziaInformatyki2014dokumentacjaPracy. 
\item Bezpośrednio w~głównym katalogu tworzony jest główny plik projektu o~nazwie main.tex z~zawartością przedstawioną w~p.~\ref{sec:PodstawowaStrukturaGlownegoDokumentu}, w~którym dołączamy pozostałe pliki.
\item Pliki tex są umieszczane w~utworzonym dla nich podkatalogu tex
\item Dla dołączanych plików graficznych wydzielony jest podkatalog fig
\end{itemize}
 

Ścieżki względne w~stosunku do głównego pliku
\verb|\input{tex/wprowadzenie.tex}|


\subsection*{Nazewnictwo plików i~rozmieszczenie w~katalogach}
Stosujemy następującą konwencję nazywania plików: na podstawie nazwy głównego rozdziału pliku formułujemy nazwę pliku, każde słowo, spójnik rozpoczynamy naprzemiennie dużą literą, pozostałe małymi, polskie znaki zamieniane na łacińskie odpowiedniki ą na a~ę na e. Pierwsze słowo z~małej litery. itp. (np. rozdział \textit{Praca w~systemie LateX} będzie znajdował się w~pliku \textit{pracaWsystemieLatex.tex}; )

\section{Strukutura logiczna dokumentu}
\subsection{Tytularia, rysunki, tabele, wzory}

Trzy formy wydzielające sekcję dokumentu:
%\section[Krótkie wprowadzenie do systemu ASAP]{Krótkie wprowadzenie do systemu ASAP wpraz ze wskazaniem przydatności do rozwiązania zadań typu CMP}
%\section*{Krótkie wprowadzenie do systemu ASAP}
%\section{Krótkie wprowadzenie do systemu ASAP}

Rysunki osadza się w~otoczeniu figure. \LaTeX{} może przy składaniu rysunki umieścić gdziekolwiek, dlatego dostępne są parametry wyrównania: 
t (top) – na górze strony, \\
b - u~dołu strony, \\
h – w~tym właśnie miejscu, \\
p – na osobnej stronie z~ilustracjami oraz \\
H - z~pakietu float, działa jak h, ale nie pozwala na wyjątki
\begin{figure}
\centering %wycentrowanie zawartości , rysunek + podpis
\includegraphics[width=3cm]{fig/pracaWzadanejDystrybucjiLinuxa/demo}
qsvgupknd
\caption{Próba wprowadzenia losowo liter z~alfabetu} %podpis rysunku
\label{fig:Alfabet}
\end{figure}



%Może kilka słów o~edytorze grafiki rastrowej Gimp.
%PrtSc print screen zapisywanie zrzutów ekranów do pliku i~późniejsza edycja w~gimpie


\subsection{Nazewnictwo etykiet}
%etykietyfdsa rg hgdfzfdszeafmug
Etykiety definiujemy przez \verb|\label{key}|

Odwołanie do rozdziału o~Linuksie \ref{sec:PracaWzadanejDystrybucjiLinuxa} a~na rysunku \ref{fig:Alfabet} jest inna nauka
%Stosowanie etykiet do pozostałych dokumentów
%mainadd.tex w~pliku opis niestandardowych środowisk

Do każdej etykiety dodajemy prefiks w~zależności od elementu na który wskazuje,
tytularia sec:, rysunki fig:, tabele tab:, równania eq:


\subsection{Stosowanie bibliografii}
\verb|\cite{nazwa_etykiety}| z~bibitem. 
\verb|\cite[s. 7]{bib_item}|
Nazywanie etykiet w~bibliografii nazwisko autora z~małej litery, rok publikacji. Gdy wiele publikacji w~tym samym roku autora, dodajemy element z~tytułu aby rozróżnić publikacje. Pozycje wstawiamy alfabetycznie.

\section{Składanie tekstu i~akapitów}
Najważniejszą jednostką podziału tekstu w~systemie \LaTeX{} (a także w~typografii) jest akapit.
Akapity rozdziela się pozostawiając pustą linię w~kodzie.
Początek rozdziału i~podrozdziału sygnalizuje się odpowiednio poleceniami: 
\begin{verbatim}
\section{tytul}
\subsection{tytul}
\end{verbatim}
Polecenie \verb|\\ lub \newline| nakazuje złamanie linii, dodatkowo \verb|\\*| zakazuje przełamania strony w~tym miejscu. \\
Instrukcje:
\begin{verbatim}
\linebreak[n ], 
\nolinebreak[n ], 
\pagebreak[n ] oraz 
\nopagebreak[n ]
\end{verbatim}
oznaczają – odpowiednio – zachętę do złamania wiersza, niezgodę na złamanie wiersza, zachętę do złamania strony, niezgodę na złamanie strony,
w miejscu ich wystąpienia w~dokumencie. 
\begin{verbatim}
\clearpage, \cleardoublepage
\end{verbatim}
rozpoczynają skład nowej strony.

Odstępy, na których nie wolno złamać wiersza, zaznacza się w~pliku źródłowym przez umieszczenie znaku tyldy \verb|„~”| zamiast odstępu.


\section{Tabele i~rysunki}
\label{sec:tabeleirysunki}


\subsection{Wstawianie rysunków}

Do wstawiania rysunków służy otoczenie \verb|figure|
\begin{verbatim}
\begin{figure}[miejsce]
zawartość, wszystko
\end{figure}
\end{verbatim}

Miejsce jest sekwencją od jednego do pięciu znaków: \verb|h| -- jeżeli jest miejsce to wstawia rysunek bez przemieszczania; \verb|t| -- wstawia na górze strony (gdy spełnia warunek wstawki), w~przeciwnym razie przenosi na następną stronę; \verb|b| -- wstawia na dole strony, gdy pozostało miejsce, w~przeciwnym razie przenosi na dół następnej strony; \verb|p| -- wstawia na stronie zawierającej wyłącznie rysunki i~tabele. Domyślną postacią jest sekwencja \verb|tbp|.

\setlength{\unitlength}{1mm}
\begin{picture}(50,80)
%dolna płaszczyzna
\put(14,23.2){$\pi$}
\put(12,22){\line(1,0){15}}
\put(12,22){\line(1,2){7.5}}
\put(19.3,37.4){\line(1,0){15}}
\put(27,22){\line(1,2){7.5}}
%górna płaszczyzna
\put(14,53.2){$\pi_2$}
\put(12,52){\line(1,0){15}}
\put(12,52){\line(1,2){7.5}}
\put(19.3,67.4){\line(1,0){15}}
\put(27,52){\line(1,2){7.5}}
%przerywana
\multiput(23, 29.7)(0,3){10}{\line(0,1){2}}
\put(23.05, 29.7){\circle*{1}}
\put(25.05, 27.7){$O''$}
\multiput(20, 29.8)(3,0){8}{\line(1,0){2}}
\put(23.05, 44.7){\circle*{1}}
\put(25.05, 42.7){$O$}
\multiput(23, 44.8)(3,0){7}{\line(1,0){2}}
\put(23.05, 59.7){\circle*{1}}
\put(25.05, 57.7){$O'$}
\multiput(20, 59.8)(3,0){8}{\line(1,0){2}}
%wymiarowanie
\put(43, 44.8){\vector(0,1){15}}
\put(43, 59.8){\vector(0,-1){15}}
\put(43, 44.8){\vector(0,-1){15}}
\put(43, 29.8){\vector(0,1){15}}
\put(44, 50.8){$c_k$}
\put(44, 35.8){$c_k$}
%kąty
\put(22.05, 30.7){\circle*{0.5}}
\qbezier(20.55, 29.7)(20.55, 32.2)(23.05, 32.2)
\put(22.05, 58.7){\circle*{0.5}}
\qbezier(20.55, 59.7)(20.55, 57.2)(23.05, 57.2)
%linie pion krzywo
\put(27.43,62){\line(-1,-4){13}}
\put(18.65,62){\line(1,-4){13}}
\put(27.43,62){\circle*{1}}
\put(18.65,62){\circle*{1}}
\put(27.43,62){$P_1'$}
\put(18.65,62){$P_2'$}
%koncowki
\put(14.5,10){\circle*{1}}
\put(31.7,10){\circle*{1}}
\put(9,7){$P_1$}
\put(33,7){$P_2$}
%przeciecia
\put(18.75,27){\circle*{1}}
\put(27.45,27){\circle*{1}}
\put(19,24){$P_1$}
\put(29,24){$P_2$}
\end{picture}
%H- z~pakietu float
\begin{figure}[H]
\centering
\begin{rotate}{30}
lorem ipsum dolor sit amet
\end{rotate} 
\caption{Przykładowy rysunek}
\label{fig:pierwszelitery}
\end{figure}


Polecenie \verb|\caption[krótkie opis wsr]{podpis rysunku, tab}|. Polecenie \verb|label| zawsze należy wstawiać za \verb|caption|, w~przeciwnym razie mogą pojawić się błędy w~numeracji. 

Do obracania dowolnego fragmentu tekstu, pudełek należy używać otoczenia \verb|rotate| z~pakietu \verb|rotating|:
\begin{verbatim}
\begin{rotate}{90}
Zawartość
\end{rotate}
\end{verbatim}


Obrazy przygotowane w~programie graficznym np. przedstawionego w~p.~\ref{sec:gimp} włącza się za pomocą polecenia \verb|\includegraphics{name}| z~pakietu \verb|graphicx}|
\begin{verbatim}
\includegraphics[width=3cm]{nazwa_pliku}
height=5cm
angle=45 %kąt obrotu w~stopniach

width=0.7\textwidth
\end{verbatim}


Przykłady wstawienie loga pwsz, ozdobej litery w~akapicie, rysunków w~tabeli, rysunku w~otoczeniu center.

\subsection{Wstawianie tabel}
Do składania tabel służy środowisko tabular. \LaTeX{} automatycznie ustala
w nich szerokość poszczególnych rubryk. Środowisko ma jeden parametr obowiązkowy, określający liczbę kolumn tabeli i~sposób ich justowania:
\begin{verbatim}
\begin{tabular}{spec-kolumn}
\end{verbatim}
Dla każdej kolumny należy w~argumencie wstawić jedną z~liter: l, r~lub c, określając w~ten sposób justowanie zawartości kolumny. Poszczególne wiersze oddzielamy instrukcją \verb|\\|, a~rubryki w~wierszu znakiem \verb|&|. Instrukcja \verb|\hline| wstawia poziomą
linię na całą szerokość tabeli.     


\subsubsection{Spisy tabel i~rysunków}
Polecenia \verb|\listoffigures \listoftables|
wstawiają te spisy automatycznie.
Elementy wprowadzane z~\verb|*| nie są umieszczane w~spisach.

%Pakiet \textbf{float} - zapoznać się z~szczegółami i~dopisać

\subsubsection{Gimp -- edytor grafiki rastrowej}
\label{sec:gimp}
Każdy w~Gimpie musi umieć
\begin{itemize}
\item Zapisywać pliki w~określonych dla pdflatexa formatach (jpg, png).
\item Ustawiać kanał alfa - tło przeźroczyste, Zaznaczać wg różnych kryteriów.
\item Kadrować i~zapisywać w~określonej rozdzielczości (np. jakie powinien mieć wymiary rysunek 45x30mm w~rozdzielczości 600dpi) określonych zdjęć. (Zrzuty ekranu PrtSc)
\item Dokonać zmiany przestrzeni barw (bitonalne, odcienie szarości, RGB, indeksowane kolory)
\item Utworzyć logo dokumentacji na zadany temat;
\item Przygotować do druku swoje zdjęcie zgodnie z~wymaganiami zdjęć do dowodów osobistych(format 35x45mm) wydrukowany na kartce o~rozmiarach 150x100mm. Zdjęcie wykonamy na zajęciach i~z niego należy wykadrować swoją fotografię. Pojedyncze zdjęcie należy umieści w~pliku tytul.tex. 
\end{itemize}


\section{Skład wzorów matematycznych}
Wzory matematyczne umieszczamy pomiędzy dwoma znakami \verb|$| wykorzystując pakiet \textbf{amsmath} oraz \textbf{amsfonts}. Celem umieszczenia numerowanego równania stosujemy środowisko \verb|\begin{equation}|.
Znaki "+", "-", "=", "!", "/", "(", ")", "[", "]", "<", ">", "|", "'", ":" wprowadzamy bezpośrednio z~klawiatury. Bardziej szczegółowe operatory dostępne są poprzez komendy zawarte w~pakiecie amsmath. Przykładowo kwantyfikator ogólny stosujemy poleceniem \verb|\forall|, e.g.: $\forall x~\in \mathbb{R} \quad x^2 > 0$.

\section{Otoczenie listing}
Pakiet listings pozwala na wstawianie kodów programów czy pseudokodu, umożliwia również formatowanie tekstu pod kątem kolorów, co zwiększa czytelność tak zapisanych tekstów. Wspiera większość popularnych języków programowania oraz jest łatwy w~adaptacji. Język, który będziemy wstawiać, definiujemy jako parametr polecenia \verb|\lstinputlisting|. \\
Wartym uwagi jest polecenie 
\begin{verbatim}
\lstinputlisting{source_filename}
\end{verbatim}
umożliwiające załączanie kodu programu z~zewnętrznych plików.
Przykładowy wynik kompilacji \LaTeX a~dla języków C++ i~php(dla drugiego zmienione zostały kolory komentarzy, słów kluczowych oraz ciągów znakowych):
\lstdefinestyle{notepad++php}{
  commentstyle=\itshape\color{OliveGreen},
  showstringspaces=false,
  keywordstyle=\color{blue},
  stringstyle=\itshape\color{black!50!white}
}

\begin{lstlisting}[language=C++,frame=single]
#include <cstdlib>
#include <iostream>
#include <conio.h>
int main() {
    int a;
    cout << "Podaj liczbe ", cin >> a;
    if(a%2==0)	cout<<"Liczba jest parzysta";
    else cout<<"Liczba jest nieparzysta"<<endl;
    getch(); // wstrzymuje wykonanie
}
\end{lstlisting}
\lstset{escapechar=@,style=notepad++php}
\begin{lstlisting}[language=php,frame=single]
<?php
/* 
Wieloliniowy komentarz 
do wpisanego kodu
*/
if(isset($_GET['wpis'])) echo "Istnieje";
else echo "Nie istnieje";
?>
\end{lstlisting}
\lstset{style=}


\section{System kontroli wersji Subversion}
SVN (alias Subversion) to system kontroli wersji, będący oprogramowaniem wolnym (na licencji Apache). Zastąpił system CVS, który jeszcze całkiem niedawno był zdecydowanie bardziej popularny. SVN służy do wersjonowania plików, najczęściej źródłowych wersji programów. Dobrze sprawdza się przy równoczesnej pracy wielu użytkowników, pracujących nad wspólnym kodem źródłowym.

\textbf{Do czego nie nadaje się SVN} \\
Nie nadaje się do wersjonowania plików, dla których nie potrafi sensownie zrobić wersji różnicowej, czyli przede wszystkim dla plików binarnych, graficznych, czy filmów. Nie znaczy to, że takich plików nie da się w~repozytorium trzymać, niemniej jednak nie będzie możliwe dobre zarządzanie nimi, czy merge’owanie. Faktem jest, że posiada znacznie lepszą obsługę tych plików niż np. CVS, ale nie do tego służy.
Plik będący dokumentem w~formacie DOC, DOCX czy ODT nie jest plikiem tekstowym, więc jeśli chcesz ze znajomymi/współpracownikami zająć się wspólną edycją dokumentów (np. pisanie pracy magisterskiej w~kilka osób), może warto zainteresować się \LaTeX-em.\\
Pozwala na równoczesną pracę nad jednym projektem wielu osób, a~w razie wystąpienia konfliktów (różnic pomiędzy plikiem w~kopii roboczej, zapisanej na dysku lokalnym, a~wersją dostępną w~repozytorium) pomaga rozwiązywać konflikt poprzez merge.
Typowy cykl pracy wygląda tak:
\begin{itemize}
\item Zaktualizuj kopię roboczą.
\begin{enumerate}
\item svn update
\end{enumerate}
\item Wprowadzanie zmian.
\begin{enumerate}
\item svn add
\item svn delete
\item svn copy
\item svn move
\end{enumerate}
\item Przeglądanie wprowadzonych zmian.
\begin{enumerate}
\item svn status
\item svn diff
\end{enumerate}
\item Być może cofnięcie pewnych zmian.
\begin{enumerate}
\item svn revert
\end{enumerate}
\item Trzy możliwości rozwiązywania konfliktów.
\begin{enumerate}
\item Porzucenie własnych zmian i~praca na poprzedniej kopii roboczej:
\begin{enumerate}
\item svn revert
\item svn resolve
\end{enumerate}
\item Zachowanie własnych zmian i~skopiowanie różnicy:\\
wyświetlenie różnicy komendą "ls":\\
MAIN - wersja oryginalna\\
MAIN.mine - nasza wersja\\
MAIN.r5 - wersja z~serwera

Skopiowane zmian na plik oryginalny i~rozwiązanie konfliktu w~konsoli:
\begin{enumerate}
\item cp MAIN.mine MAIN
\item svn resolved MAIN
\end{enumerate}
\item Scalanie obydwu wersji w~jedną:\\
Ręczne wprowadzenie zmian w~pliku MAIN, usunięcie znaczników oraz dodanie nowej treści.
\begin{enumerate}
\item svn resolved README
\end{enumerate}
Zaktualizowanie kopii roboczej, sprawdzenie czy nie powstał nowy konflikt, przesłanie zmian do repozytorium.
\end{enumerate}
\end{itemize}

Do naszych zastosowań subversion wydaje się być rozsądnym narzędziem, przy założeniu roztropnego korzystania z~jego opcji.